Skip to content

docs: Diátaxis site from Org pages, with API pages from the code - #22

Merged
HaoZeke merged 3 commits into
mainfrom
docs/diataxis
Nov 16, 2026
Merged

HaoZeke merged 3 commits into
mainfrom
docs/diataxis

Conversation

@HaoZeke

@HaoZeke HaoZeke commented Nov 16, 2026

Copy link
Copy Markdown
Contributor

The site was the README as one Sphinx page, with no tutorial, no task-sized guides and nothing linkable by name.

  • Org pages under docs/orgmode/ are exported to reStructuredText and built by Sphinx with warnings and unresolved names as errors.
  • docs/tools/zig_api.zig writes one API page per module from the doc comments, and the site publishes an objects.inv for intersphinx.
  • check_site.py checks internal links and anchors and that no page names a site; lychee checks external links.
  • pixi.lock pins the tools, so dependabot no longer watches docs/requirements.txt.
  • docs.yml replaces pages.yml and publishes with the workflow's own GITHUB_TOKEN.

First pages: the tutorial, the how-to on stopping a slow child, the explanation of checks on the open descriptor, and the compatibility table. Three news fragments are included.

The site was the README's text as one Sphinx page, with COMPAT.md and
RELEASING.md beside it and the Zig autodoc at api/. It had no
tutorial and no task-sized guides, and nothing on it could be linked
by name: another tool's docs could cite a zig-common call only as
text.

The documentation template builds it now. Org pages under
docs/orgmode/ are exported to reStructuredText and built by Sphinx
with warnings and unresolved names as errors. docs/tools/zig_api.zig
writes one API page per module from the doc comments, and the site
publishes an objects.inv of every pub declaration, which the other Zig
tools' sites can link into through intersphinx. check_site.py checks the
internal links and anchors, and that no page names a site; lychee
checks the external links, skipping eb-stack.rgoswami.me, whose bot
challenge answers 403. pixi.lock pins the tools, so dependabot no
longer watches docs/requirements.txt.

The first pages are the tutorial, "Write a small tool on zig-common",
the how-to on stopping a slow child, the explanation of checks on the
open descriptor, and the compatibility table. RELEASING.md is linked
from the contributing page. The docs workflow replaces pages.yml and
publishes with the workflow's own token.
The API pages and the autodoc show each declaration's doc comment, and
its first sentence is the summary in the module's list. 83 of the 164
pub declarations had none, so their entries were a bare name and a
signature. Each now says what it is or does, with the units, limits
and errors the code has. Only comments change.
The first pages covered one task and one design choice. These are the
rest:

- how-to guides: replace a file and keep its access control lists,
  keep private state in /tmp, compress logs and keep them marked,
  match a Python tool's output, and upgrade zig-common in a tool;
- explanations: process groups and deadlines, system calls without a
  C library, and Python compatibility;
- reference: the messages, exit statuses and version line of cli.

The code on each how-to page was built against this tree and run as
the page says.
@HaoZeke
HaoZeke merged commit c4be701 into main Nov 16, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant